This is a short introduction to the JBoss modules descriptors file which controls the generation of the JBoss modules folder with the smartics JBoss Modules Maven Plugin.

This plugin is useful for developers using Maven, who want to add their libraries or frameworks as modules or extensions to a JBoss AS 7 server.

For a general introduction to the smartics JBoss Modules Maven Plugin, please refer to Maven Plugin to generate a Modules Directory for JBoss AS 7 or to articles about JBoss modules on this blog.

Outline: modules

The basic structure of the smartics JBoss modules descriptors XML file is this:

<modules xmlns="http://smartics.de/ns/jboss-modules-descriptor/1">
  <module name="...">
  </module>
  <module name="...">
  </module>
  ...
  <module name="...">
  </module>
</modules>

You see a list of module descriptors, for each of them a JBoss module folder will be created, if a dependency referenced from the Maven POM matches. For each dependency that is not matched by a module descriptor, a default module will be created.

Outline: module

The module element, with mandatory name and optional slot attributes, has four major sections:

<module
  name=""
  slot="">
  <directives>
    ...
  </directives>

  <match>
   ...
  </match>
 
  <apply-to-dependencies>
    ...
  </apply-to-dependencies>

  <apply-to-module>
    ...
  </apply-to-module>
</module>

Directives

The directives control the generation of the modules folder.

Match

The match element selects Maven dependencies by the groupId and/or artifactId. All matching artifacts are added as resource roots (i.e. resource-root elements) to the generated module.xml.

Apply-tos

So there are basically two generated types of entities within the generated JBoss module descriptor (module.xml):

1. module – in form of a module.xml
2. dependencies – in form of dependencies/module elements within a module.xml

Not all relevant information for the JBoss module descriptor can be derived from information in the Maven POM. To apply additional information to these generated entities use apply-to-module and apply-to-dependencies respectively. apply-to-module applies (i.e. adds or corrects) information in the generated module.xml. apply-to-dependencies applies (adds or corrects) information in matched dependency modules.

The following sections give some examples on these elements.

Directives by Example

A simple directive is to skip the generation of a module. The use case it as follows: You have a dependency to an artifact, but the artifact is already provided by another JBoss modules folder (e.g. is part of the public API delivered by the JBoss AS itself).

<directives>
  <skip>true</skip>
</directives>

Match by Example

As mentioned above, this allows to catch Maven dependencies by their artifact coordinates. Only group and artifact ID are supported.

<match>
  <includes>
    <include>
      <groupId>commons-.*</groupId>
      <artifactId>commons-(.*)</artifactId>
    </include>
  </includes>
</match>

It is allowed to use regular expressions in either of the matching elements, but they should be given only on one include. You may also add excludes to filter on the inclusions.

Apply-to-Dependencies by Example

If you want to modify a generated dependency, e.g. if you want to set the export property to true, use this:

<apply-to-dependencies>
  <dependencies>
    <match>
      <includes>
        <include>de.my.module..+</include>
      </includes>
    </match>
    <apply>
      <export>true</export>
    </apply>
  </dependencies>
</apply-to-dependencies>

Within a dependencies element there is a match element that matches modules by their name to have the information in the apply element applied.

There are other elements like services, optional, or imports/exports. For details please refer to Module descriptors.

Apply-to-Module by Example

If you want to add additional dependencies, use the apply-to-module element. For instance you may want to add a dependency to the public API javax.api provided by the JBoss AS:

<apply-to-module>
  <dependencies>
    <module name="javax.api" />
  </dependencies>
</apply-to-module>

There are other elements like exports, main-class, or properties. For details please refer to Module descriptors.

Conclusion

This has been a short introduction on the smartics JBoss modules descriptors XML. In this overview we presented the building blocks of this descriptor and short examples to get you started in using the smartics JBoss Modules Maven Plugin.

We plan to add use case centric articles in the future to give you a deeper understanding on the generation task.